/**
 *
 * The MIT License
 *
 * Copyright (c) 2008 Board of Trustees, Leland Stanford Jr. University. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:

 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package org.macdadi.core.client.auth;

import com.google.gwt.core.client.GWT;
import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.ServiceDefTarget;

/**
 * This service provides methods to authenticate a user, establish a time-limited
 * authenticated session, end a session (logout).
 *
 * @author Ben Suter <ben.suter@gmail.com>
 */
public interface AuthService extends RemoteService
{
    /**
     * Authenticate a user. If the authentication succeeds, either
     * a new session is established, or an existing session is
     * extended.
     *
     * @param email     identifies the user (case-sensitive)
     * @param password  authenticates the user (case-sensitive)
     * @return          true if the credentials are valid
     */
    public AuthenticatedUser login(String email, String password);

    /**
     * Terminate the specified user's session. The user must be
     * currently authenticated for this method to succeed.
     *
     * @param user  a user with a current session
     * @return      true if no session remains for this user
     */
    public boolean logout(AuthenticatedUser user);

    /**
     * Find the authenticated user for the specified session.
     * If the session is not valid, or if no such session exists,
     * null is returned.
     *
     * @param   email       the email (username) of the user
     * @param   authToken   a current session identifier
     * @return              null if session invalid or non-existent, otherwise an authenticated user
     */
    public AuthenticatedUser getUserForSession(String email, String authToken);

    /**
     * Determines whether the user authenticated with <code>authToken</code
     * is permitted to view domain for the specified project. Generally the
     * result is true if the project is public or the user is an active
     * member of the project.
     *
     * @param authToken     token identifying an authenticated user
     * @param projectId     the project in question
     * @return              true if the user may view domain for the project
     */
    public boolean isAuthorizedProjectRead(String authToken, int projectId);

    /**
     * Determine whether the user authenticated with <code>authToken</code>
     * has permission to perform <code>operation</code> against <code>target</code>
     * for the specified project. This method is intended for use by client-side code
     * that exposes editing controls only to users who are permitted to perform such
     * modifications.
     *
     * To check whether the current user is permitted to modify a goal, the call
     * would look something like this:
     * <code>isAuthorizedOperation(currentAuthToken, currentProjectId, TARGET_GOALS, OPERATION_EDIT);</code>
     *
     * Implementation note: This method invokes the <code>auth_check_operation</code>
     * stored procedure, which is used internally by other stored procedures to
     * check the role-based permissions for any modifications to domain.
     *
     * @param   authToken   token identifying an authenticated user
     * @param   projectId   identifies the project
     * @param   target      a domain collection, one of the TARGET_XXX constants
     * @param   operation   the type of modification, one of the OPERATION_XXX constants
     * @return              true if the user may perform the modification 
     */
    public boolean isAuthorizedOperation(String authToken, int projectId, String target, String operation);

    public static final String OPERATION_CREATE = "create";
    public static final String OPERATION_UPDATE = "update";
    public static final String OPERATION_REMOVE = "remove";

    public static final String TARGET_GOALS = "goals";
    public static final String TARGET_OPTIONS = "options";
    public static final String TARGET_STAKEHOLDERS = "stakeholders";
    public static final String TARGET_PREFERENCES = "preferences";
    public static final String TARGET_IMPACTS = "impacts";
    public static final String TARGET_PROJECTS = "projects";
    
    /**
     * Utility/Convenience class.
     * Use AuthService.App.getInstance() to access static instance of AuthServiceAsync
     */
    public static class App
    {
        private static AuthServiceAsync ourInstance = null;

        public static synchronized AuthServiceAsync getInstance()
        {
            if (ourInstance == null) {
                ourInstance = (AuthServiceAsync) GWT.create(AuthService.class);
                ((ServiceDefTarget) ourInstance).setServiceEntryPoint(GWT.getModuleBaseURL() + "org.macdadi.core.Core/AuthService");
            }
            return ourInstance;
        }
    }
}
